Mac Magazin/MacEasy 19/Mac Magazin and MacEasy Magazine CD - Issue 19.iso/Spiele & Edutainment/BMAPEdit ƒ/BMAPEdit doc (text)

Text File | 1996-02-02 | 48KB | 858 lines

BMAPEdit Version 3.0
(c)1993-96 Carl R. Osterwald

Introduction

BMAPEdit is a Macintosh application to create and edit maps for Bolo, the
multi-player distributed tank battle game written by Stuart Cheshire.  BMAPEdit
reads, edits, prints, and creates files (of type 'BMAP') for use with Bolo.  It
has been designed to provide you, the people who enjoy playing Bolo, with the
tools needed to quickly and efficiently make creative maps.

BMAPEdit is shareware.  If you like and use BMAPEdit, please send $10.00 to:
    Carl R. Osterwald
    75 S. Dudley St.
    Lakewood, Colorado 80226

This program may be freely distributed provided this documentation file is
distributed also.  It may not be sold commercially.  This version is free to
previously registered users.

Please send any comments, suggestions, or, most importantly, bug reports to:
    Internet:  [e-mail]
    or by physical mail to the address above.

1.    Acknowledgments
*    Stuart Cheshire--of course, who wrote Bolo and provided the code to read
    and write Bolo map files.  Stuart also co-developed the code for the
    graphical previews that appear when opening map files.
*    Tom Barrett & Stuart Cheshire provided the Bolo preview graphics code.
*    Scott Knaster & Keith Rollin wrote "Macintosh Programming Secrets," highly
    recommended for anyone writing Macintosh code.
*    Forrest Tanaka developed the offscreen graphics code that is contained in
    the Apple DTS Tech Note, "Principia Offscreen Graphics".
*    Peter Lewis developed the random map generator & growth algorithms.
*    Charles Brabec granted permission to incorporate his Birdman's Map Maker
    source code as the tiled random map generator.
*    Phil Parilla developed the self-avoiding random walk-maze algorithm.
*    Jim Stout wrote the 3D buttons that are a part of Jim's CDEFs and available
    free of charge.
*    Christer Ericson wrote the function that calculates the area of a QuickDraw
    Region.
*    And especially all the beta testers whose hard work and patience dealing
    with less-than-optimum programming have allowed BMAPEdit to become what it
    is today.  Many thanks to:

    Thomas Apodaca, Aaron Bratcher, Chip Benowitz, Charles Dillon, Chris Hanson,
    Eric Hiris, Bill Ingalls, Brian Keyes, Gavin Kistner, Dan LaLiberte, Russell
    Mast, Phil Parilla, Caine Schneider, Andrew Tennant, & John White.

2.    System Requirements & Capabilities
*    Color Quickdraw (not available on Macs with 68000 CPUs such as Classics or
    SEs)
*    750 kBytes of memory (prefers 1 MByte)
*    System 7.0 or greater
*    Accelerated for Power Macintosh (optimized for PowerPC 604 microprocessors)
*    Macintosh drag and drop (with System 7.5 or greater)
*    Balloon help
*    B&W printing (requires a PostScript printer)
*    Color/grayscale printing (requires a PostScript Level 2 printer)

BMAPEdit does not require a color monitor, but color will allow you to take full
advantage of the display capabilities of BMAPEdit.

Each open map window requires 66 kBytes of memory.  BMAPEdit will warn you if
the amount of free memory drops to dangerous levels as more map windows are
opened.  The amount of free memory is displayed in BMAPEdit's About Box (choose
About BMAPEdit in the Apple menu).

The amount of memory allocated to BMAPEdit affects the drawing speed.  The
initial memory size is 1750 kbytes, which lets BMAPEdit use the maximum amount
of memory for its offscreen drawing buffer.  If this memory size is reduced,
drawing speeds will be somewhat slower.  In case you need to run with less
memory, you change it by quitting the application, selecting the BMAPEdit icon
(don't double-click it), and choose Get Info... in the Finder's File menu.  You
can then adjust the memory size as your needs dictate.

BMAPEdit versions earlier than 3.0 would run under System 6.0.4 or later.  If
you are still using System 6, you should not upgrade to a version later than
2.0.1.

Balloon help is provided for all menus, the ToolBox, and a number of dialogs.
It can be activated from the Guide (help) menu in the right hand side of the
menu bar.  Help balloons will then appear as the mouse is moved (after balloon
help is first activated, it can take several seconds for the balloons to start
appearing).

BMAPEdit is a so-called 'fat' application, which means it contains code to
operate on either 68000 or PowerPC Macintoshes.  A modest amount of disk space,
about 200 kBytes, can be saved by removing whichever version is not needed for
your computer.  If necessary, this space can be saved by using a utility program
such as StripFat, which is available from the popular Info-Mac FTP archive
servers.

3.    Bolo Maps
Bolo maps use a grid of 256 by 256 squares.  Squares are numbered left-to-right
and top-to-bottom starting at 0 and ending at 255.  Of these squares, the
outermost 10 squares on all sides are filled with mines by Bolo (the outer
minefield) and cannot have terrain placed in them.  Although refueling bases and
pillboxes can be located in the outer minefield, the author of Bolo discourages
this and a warning dialog box asking for confirmation is displayed when
placement in the outer minefield is attempted.  Also, Bolo does not allow any
terrain except deep water in an additional 10 square border inside of the mine
field squares.  While this deep water border is intended for start squares (the
invisible squares that define where tanks can enter the game), bases and
pillboxes may also be located here if desired.  All regular terrain other than
special squares (bases, pillboxes, and start squares) is restricted to squares
20 through 235 horizontally, and 20 through 235 vertically.  The border of this
area is called the terrain mapping limit rectangle in BMAPEdit.

BMAPEdit does not read old-style 'resource' Bolo map files.  These older files
may be read and converted by opening them with the Bolo application and then
saving to a new file.

4.    Map Windows
The Bolo display shows the map squares in 16x16 pixel rectangles.  This
corresponds to the Preview mode in the BMAPEdit Mag menu.  Four other modes,
12x12, 10x10, 8x8, and 5x5, display the map data in reduced Bolo graphics.
Start squares are shown as a tank on a boat in deep water (except for 5x5, which
use a small arrow), pointed in the same direction as the start square's
direction.  Initial ownership of bases and PBs is indicated as follows:  bases
and PBs with ownership of 1 are drawn in green (friendly); bases with ownership
greater than 1 are drawn in red (hostile) (also see the Options menu section).

The remaining display modes, 3x3 and 1x1, use single colors to represent map
terrain.  In B&W 3x3 and 1x1, land squares are black and water squares are
white.  In 1x1 magnification, an entire Bolo map can be viewed in a window of
only 256 by 256 pixels.  The colors used for the reduced display modes have been
selected to allow distinction of terrain on monitors with only 16 colors
available.  A key to the reduced colors is in the ToolBox below each of the
terrain icons.  Mines are shown as a yellow dot centered in terrain squares at
3x3, and are not displayed at 1x1.  Start squares show up as a small red arrow
or dot.

The border of the terrain mapping limit rectangle can optionally be displayed
(see the preferences item under the Edit menu below).  The horizontal and
vertical map coordinates are displayed in the floating ToolBox palette as the
mouse is moved across the map window.

Two other display options are ownership of bases and pillboxes, and special
square numbering.  These options, which cannot be enabled simultaneously, place
small numbers over the special squares.  Blue numbers are used for bases, red
numbers for pillboxes, and green numbers for start squares.

Special square numbering is the logical ordering of these objects in the map
data; it does not have any visible effects on the map.  In the Bolo information
displays, bases and pillboxes are indicated starting with number 1 in the
top-left corner of the displays and continuing left-right top-to-bottom to
number 16 (or to the total number of bases or PBs).  Bolo itself has two
options, pillbox labels and base labels, that display numbering.  However, the
Bolo numbers start with zero rather than the more conventional one.  Thus,
Bolo's pillbox and base labels will be one less than the numbers displayed in
BMAPEdit.

BMAPEdit can also display the range of pillbox shots, according to a checkbox in
the preferences dialog.  There are several important ranges in Bolo, as follows:
1) the maximum distance a tank can shoot is 6 1/2 squares from the tank center,
2) the distance at which a pillbox will begin shooting at a tank is 8 squares
from the center of the pillbox, and 3) the maximum distance a pillbox shot can
travel is 8 1/2 squares from the center of the pillbox.  BMAPEdit displays this
last range as a white circle around pillboxes.

Map windows can be scrolled with the scroll bars, with the 'grabber' hand that
is activated by the pressing the space bar, or with the page up, page down,
home, and help keys on extended keyboards.

5.    Map Drawing
BMAPEdit uses a 'foreground – background' style where the foreground terrain is
defined by the icon selected in the ToolBox, and the background terrain is
selected through a popup menu at the bottom of the ToolBox (a background terrain
popup menu also is located in the preferences dialog).  All drawing applies the
foreground terrain to make changes, while the background terrain is applied when
a selected region is moved, rotated, reflected, or cleared.

Drawing is done with five basic methods: pencil, line, filling, framing, and
painting.  Of these, filling and framing are performed on regions defined with
the selection tools in the ToolBox (the rectangle, rounded rectangle, oval,
polygon, and lasso tools) by using the corresponding commands in the Utilities
menu.  Pencil drawing, line drawing, and painting are done by clicking with the
respective tools from the ToolBox. Important--line drawing, filling, and framing
apply the pattern currently selected in the Patterns menu, where a black pixel
in the pattern changes the terrain in the map squares affected to the
foreground, and white pixels cause no changes.  Many effects can be achieved
with the patterns, including, for example, perfect 'checkerboard' mine fields.
Such a mine field would be laid down through the 50% gray pattern.  When
BMAPEdit is first opened, the pattern defaults to solid black.

Pencil drawing changes individual map squares to the foreground terrain.  It
operates in the traditional 'paint' program style.  As the pencil is moved
across a map, the destination square that would be changed by a click is
highlighted with an open white box (except for magnifications less than 8x8).
Pencil drawing is also the primary way special squares--refueling bases,
pillboxes, and start squares--are added to a map.  Filling, framing, painting,
and line drawing do not apply to special squares.  Therefore, selecting the
base, pillbox, or start square icons in the ToolBox automatically selects the
pencil tool.  Start squares are added to a map by clicking and dragging the
pencil until the desired direction is indicated.  Note--the direction of existing
start squares can be also changed by clicking and dragging with the pencil.
Special squares are deleted by clicking them with the bulldozer tool from the
ToolBox.  The bulldozer can also be activated from the pencil tool by holding
the option key down.

Lines are drawn after a line segment has been selected by clicking and dragging
with the line tool.  The line produced is affected by the current pattern, and
its size is determined by the current line size setting in the preferences
dialog.  The line tool can also be used to make square blocks quickly by
selecting an appropriate line size and clicking on the map without dragging.
Lines drawn in road, water, or deep water terrain at line size equal to 1
produce a path that is traversable.  Holding down the option key while dragging
a line with the line tool causes BMAPEdit to make a randomly-walked path with a
line size of 1 (the line size setting in this case is ignored).

Filling is performed by selecting a region with a selection tool (see the
ToolBox discussion below) and choosing the Fill Selection item in the Utilities
menu.  Framing is similar, except that the line width used is determined by the
current line size setting in the preferences dialog.  Two framing operations are
available--either inside the selection boundary, or outside.

Painting is done by clicking with the paint bucket tool.  The paint bucket
simply changes all the identical terrain squares adjacent to the click location
to the foreground terrain.  It operates in the traditional 'paint' program
style.  If the paint bucket is applied inside a selected region, painting is
clipped to the selection boundary and will not go outside the boundary.
Painting can also be done with the random blob tool which works similarly to the
paint bucket, but stops when a small irregular shape is produced, rather than
changing all adjacent identical terrain.  Note--holding the option key down while
clicking with the paint bucket does not change terrain, but rather selects the
region that 'paint' would flow to (see the lasso tool below).  Holding both the
shift and option keys down extends an existing region selection.

Mines and special squares represent special cases.  Mines can only be applied to
existing swamp, crater, road, forest, rubble, or grass squares.  Attempting to
place mines on any other types of terrain is ignored.  Start squares can only be
placed in deep water.  If other terrain is subsequently applied to a start
square, the start square is removed.  Also, bases and pillboxes 'float' above
whatever terrain they have been placed in, including deep water.  The terrain a
base or pillbox sits on is what a map square becomes when that base or pillbox
is moved during a game (currently, Bolo allows only pillboxes to be moved).
Note--it is possible to create completely unusable refueling bases by locating
them in deep water, with all adjacent squares also deep water.  A tank can land
at the base and refuel, but because boats cannot remain in deep water
unoccupied, there is no way to leave the base without dying in deep water.

Note--Bolo maps are currently limited to 16 of each type of special square
(bases, pillboxes, and start squares).  BMAPEdit, however, allows up 32 bases
and pillboxes each to be placed on maps.  This is allowed because it is easy to
create more than 16 when copying and pasting selections.  Rather than
automatically eliminating the extras, BMAPEdit places them and allows you to
decide which ones to delete.  This feature also allows you to examine different
options before deciding which is best.  When saving such a map, however, only
the first 16 of each are put into the map and a dialog appears telling you that
the extra bases and pillboxes were not included.

6.    The ToolBox
The ToolBox is a floating window/palette that is divided into five sections.
These sections are, from top to bottom:  1) the foreground terrain selection,
2) current special square counts, 3) the tool palette, 4) the map coordinate and
area of selection display (both in units of map squares), and 5) the background
terrain popup menu.

The foreground terrain selection section is an array of fifteen terrain types,
represented as icons, that can be applied to Bolo maps.  These icons are
identical to the terrain squares as drawn by Bolo in a game.  Just below each
icon is a color bar that shows which color is used to represent that terrain in
the reduced color drawing modes (the color bars do not appear in B&W).  The
bottom row of icons in the terrain palette are the special squares, from left to
right, refueling bases, pillboxes, and start squares.

Clicking the zoom box in the upper right toggles the ToolBox between its full
size and a minimum-sized bar.  Note--the Window Shade function introduced with
System 7.5 performs the same function when double- or triple-clicking on a
window's title bar; they are not entirely compatible.  Once the ToolBox has been
minimized with the zoom box, Window Shade clicks do not affect it--it must be
restored with the zoom box.

The sixteen tools in the tool palette are described next in left-to-right,
top-to-bottom order.

The pointer tool performs three functions:  dragging selections, dragging
special squares, and double-clicking special squares.  All dragging is pinned to
the terrain limit rectangle which was defined above, except when Macintosh drag
and drop is available.  Moving selections by dragging them is straightforward,
and, after the move, the terrain in the selection is replaced with the
background terrain.  Once a selection has been dragged, it can be moved again
without affecting the map until the selection is 'set' (or the 'paint has
dried') by selecting another tool, pressing the escape or tab keys, or by
switching to another map window.  See the drag and drop section below for more
information about dragging.

Special squares may be relocated without having to first select them with one of
the selection tools.  Simply click and drag them to the new location.  Notice
that this is different from dragging a selection because the terrain under the
special square is not moved.  Also, special square drags do not use the Drag
Manager (see below) and thus cannot leave the starting window.

The settings of special squares may be adjusted by double-clicking them.  A
double-click brings up a dialog window that will allow you to make whatever
changes you desire.  The special square dialogs are described in more detail
below.

Bases, pillboxes, and start squares are deleted by clicking them with the
bulldozer tool, which is also activated by pressing the option key while the
pencil tool is selected.

The magnifying glass is used to switch display modes.  Holding the option key
down while clicking switches to a lower magnification, while a normal click
produces the opposite effect.  Display modes may also be switched with the  +
and - keys, as well as the number keys.  The control key functions as a keyboard
shortcut for the magnifying glass.

The pencil and line tools are used for pencil and line drawing, as described
above.  Dragging with the shift key down restricts lines to horizontal,
vertical, and diagonal directions.

The random blob and paint bucket tools have been described above in the drawing
section.

Rectangle, rounded rectangle, and oval regions are selected with the next three
tools, respectively.  Dragging with the shift key down causes square and circle
regions to be selected, and if the option key was pressed when the mouse was
clicked, the selections expand from the click location, causing the selection to
be centered at this point.  Centered selections can be an even or odd number of
squares wide and high, depending on the where the initial click is relative to
the center of the square.  Option-clicks near the center produce odd width and
height selections, otherwise the selection is even number of squares wide and
high.

Polygons are selected with the polygon tool.  Each mouse click in succession
adds another point to the polygon, up to a maximum of 128 points.  A
double-click adds a final point and closes the polygon.  The previous polygon
point can be deleted, before the final point is added, by holding the option key
down and clicking.  Note that a polygon does not have to be open, i.e. a series
of points can be closed by 'doubling back' to the first point.  The sequence of
line segments produced can be framed, but not filled.

The lasso is used to select regions of existing terrain.  Terrain to be selected
is surrounded by a series of points in a manner identical to polygon selections
(the final point is added with a double-click).  The selection is then shrunk to
an outline of terrain dissimilar to the terrain at the first point selected.

Selections can rotated or reflected perpendicular to a line with the rotator and
reflector transformation tools.  The original selection region is replaced with
the background terrain unless the selection is not yet 'set' (or the 'paint is
still wet').  After rotation or reflection, the selection can be dragged into
final position without disturbing existing terrain until the selection is 'set'.
Note that it is possible for special squares to be lost during the
transformations.  Two adjacent specials can transform to the same square,
causing one to be removed.  Also, in very small selections, i.e. one square, the
transformation can result in loss of the special square, especially at rotation
or reflection angles that are not even multiples of 45 degrees.  Note that
holding the shift key down while clicking with the rotator and reflector tools
constrains the transformation angle to multiples of 45 degrees.

Finally, you can add lettering to maps with the text tool.

7.    Drag and Drop
Introduced with Macintosh System 7.5 was the ability to drag information between
windows, even those of different applications.  BMAPEdit uses the Drag Manager
for dragging map selections, and also accepts information transferred from other
applications.  Thus, it is possible to drag map pieces, or even entire maps, to
other map windows.  Drag and drop is really an extension of cut and paste,
although it operates independently from the clipboard.

Dragging selections with the drag manager is nearly identical to when it is
absent, except that selection outlines are allowed to leave the starting window.
 The selection outline snaps to map squares until it is outside of the window,
at which point this is no longer possible.

Dragging from map windows--selections dragged out map windows will contain the
map information in three formats, called drag flavors:  1) BMAPEdit internal map
data, 2) text, and 3) Quickdraw picture format (PICT).  The last two formats are
intended for exporting map information to other applications, while the internal
flavor is for transferring information between BMAPEdit windows (note that the
text flavor can be disabled with a checkbox in the preferences dialog).

There are two drag destinations external to BMAPEdit that are very useful for
map making--the scrapbook and the desktop.  Selections dragged to the scrapbook
will show the picture representation, and will list the other drag flavors
contained.  If the desktop is the final destination of a drag, the Finder will
create a so-called clipping file containing the drag information.
Double-clicking a clipping file causes the Finder to display its contents.  Both
of these can be used to store often-used map pieces.

Dragging to map windows--when a map window becomes the destination of a drag
flavor that BMAPEdit can accept, the two-pixel white border around the map
display is highlighted.  BMAPEdit accepts drags of text, pictures, and its own
internal drag flavor.

See the Text Import/Export section for more information about text translation
of map data, and the Edit menu section for details of importing pictures.

8.    Snap-To-Grid
BMAPEdit has the ability to restrict drawing operations to an invisible grid.
The grid defaults to the minimum size of one square, but can be set to larger
values with the Grid Size item in the Options menu (see the Menus section
below).  A grid size of three, for example, will force the cursor to map squares
evenly divisible by three, e.g., squares 3, 6, 9, 12, etc.  When dragging
selections or special squares, objects are moved in offsets from the starting
locations that are multiples of the grid size.

The X-Y map coordinate display in the ToolBox snaps to the current grid setting.

9.    Random Utilities
BMAPEdit has special utilities for adding random features to Bolo maps.  Several
of these--random bases & PBs, random maps, random fills, random frames, make
island, maze fill and city fills--are accessed through the Utilities menu and are
discussed below.  Small random shapes or 'blobs' can be made with the random
blob tool, or with the pencil tool and the shift key pressed.  The random shape
only 'grows' on terrain identical to the click location in a way similar to the
paint bucket Random 'walks' or lines can be added with the line tool and option
key held down.

10.    Menus
File menu-- The File menu operates on Bolo maps, text files, and picture files.
Important features of these menu items are described below.

When the Open item in the File menu is selected, and System 7 is available,
BMAPEdit displays a custom open file dialog box.  As map files are highlighted
in the file list, the map data is read from the file and a small preview of the
map is displayed in the left-hand side. Neither the outer mines nor the start
squares are shown.  In B&W, land is black and water is white, except for bases
and PBs, which are white.  This graphical feedback is intended to give visual
clues about the file being opened, as opposed to selecting a file by just the
file name.

BMAPEdit performs a validity check on the special squares when an existing map
is opened.  The check detects bases, pillboxes, or starts that occupy the same
squares, and looks values of armor, direction, shot speed, shells, mines, and
ownership are within the limits defined for Bolo maps.  If problems are found, a
dialog box is displayed asking for permission to correct the problems.  Out of
range values are set to default values, and extra specials in a single square
are removed.  If you change your mind, the Undo command in the Edit menu will
reverse all the corrections.

A warning dialog is displayed when a map that has no start squares is saved
because such a map is not usable as a game map.

If the option key is pressed while selecting the Close or Save items, all map
windows currently open will be closed or saved.

The Open Text/Save as Text items allow importing and exporting Bolo maps as text
files that can viewed without the Bolo application or a map editor such as
BMAPEdit, using a standard set of ASCII characters.  See the section on text
import/export for complete details of the character set.

Saving a map as a PICT produces a PICT (Quickdraw picture) file that shows the
Bolo map drawn according to the export format selected in the preference dialog.
Please note that these files can be quite large at larger magnifications and if
color is desired.

The Launch Map item allows you to start a new Bolo game using the top map window
from BMAPEdit.  If the map has not been saved, you will be asked to save the map
before Bolo is launched.

Bolo map files can be printed in B&W to a PostScript printer, or in
color/grayscale to PostScript Level 2 printer, according to the settings in the
LaserWriter print dialog window.  The output is intended as a navigational aid,
and larger maps are printed with progressively smaller squares.  Color/grayscale
printing will require significantly more time to print than B&W, and will cause
a PostScript error if the printer selected in the Chooser is not a PostScript
Level 2 printer.

Edit menu-- The Edit menu follows the standard Macintosh format.  Map regions
that have been copied or cut and then subsequently pasted can be dragged into
final position using the pointer tool.  Map data that is in the clipboard is
converted to a PICT image according to the export format selected in the
preferences dialog, for export to other applications.  If auto conversion item
in the preferences dialog is checked, clipboard data is converted to PICT format
automatically whenever BMAPEdit is switched to the background, or when Quit is
selected in the File menu.  If automatic conversion is not enabled (the default
setting), clipboard data can always be converted with the Convert Clipboard
item.  Note--large selections can consume large amounts of memory, especially
when color conversion is requested.  It is therefore possible for the conversion
to fail if not enough memory is available.

PICT images that are in the clipboard can be pasted into a map.  Terrain is
determined by the colors in the image, and should correspond to the color bars
in the ToolBox.  Red and yellow should be avoided as these are used for display
of special squares and therefore are converted to the background terrain.

Select All selects a rectangular area that bounds the entire map while ignoring
deep water.  If the map is empty, the entire editable area is selected.

The Clone item performs a two-step copy-paste operation that allows a copy of
the selected area to be dragged away while leaving the original terrain
untouched.  Because the pasted selection is directly over the original, there is
no visible change to the map.

The Transform Again item repeats the last move, rotation, or reflection
operation on the current selection.  Thus, if the last operation was a
five-square move, transform again will move whatever is currently selected by
the same offset.  With the combination of clone and transform again, it possible
to create a large number of identical items, and is especially useful in making
tiles for the tiled random map generator (see below).  To do this, draw the
first tile, select the tile, clone it, then drag it to the next position.  Then
repeatedly clone and transform to make a number of tiles.  The command keys
equivalents (cmd-\ and cmd-,) make the process almost instantaneous.

The Preferences item presents a dialog window in which all of the options for
BMAPEdit are selected.  The settings in the options menu are preserved in a
preferences file.  Many of these have been discussed previously.  The Random
Fill % item allows the approximate percentage of a random fill to be selected.
Random fills are discussed in greater detail below.  The Show Numbering and Show
Ownership checkboxes are mutually exclusive; they cannot both be checked at the
same time.  Another checkbox determines if text representations of map data are
sent when dragging selection out of BMAPEdit with the Drag Manager (see the drag
and drop section above).

Mag menu-- The Mag menu is used to switch magnification display modes.
Command-key equivalents are provided for convenience.  The Increase/Decrease
items change magnification by one level and can be accessed through the +/-
command keys on the keyboard or keypad.

Patterns menu-- The Patterns menu is used to select the Quickdraw pattern that is
used for line drawing, filling, and framing selections.  It defaults to solid
black, as discussed above.

If you are familiar with editing resources, using ResEdit or other resource
editors, you can edit the patterns provided in BMAPEdit's  resource fork, or add
new ones.  The patterns are loaded from resource type 'PAT#', ID 128.  Editing
the solid black pattern, the first one in the list, is not recommended because
without it, there is no way to perform solid fills and lines.

Utilities menu-- The Utilities menu contains an assortment of operations that can
be performed on Bolo maps.  These operations are now described in order.

The Fill Selection and Frame Selection items were discussed above in the Drawing
section.

The Random Fill item is used to randomly distribute the foreground terrain
throughout a selection.  The amount of filling will be close to (but not
precisely) the percentage as set in the preferences dialog.  This setting, which
is the probability a single square will be filled, defaults to 20%.  Random
fills of boats only affect existing water terrain (not deep water).  The Random
Frame item operates on rectangular or polygon selections and performs a random
walk from point-to-point using the foreground terrain and a line size of one
square.  Also, see the keyboard shortcuts section for further information about
producing random terrain.

Frame Outside was also discussed above.

The next three items, Make Island, Maze Fill, and City Fill, generate random
fills in selections.  For the maze and city files, if the current selection is
not rectangular, the result is clipped to the selection.

Make Island produces a randomly shaped island inside the selection, and then
performs a fill, random fills, and then a frame as directed.  Popup menus allow
selection of the island and outline terrains, including no change if desired.
If a polygon is selected, the polygon is used and a random shape is not
produced.  Small, one-square pinholes can be prevented with a checkbox selection
in the Make Island dialog.

The Maze Fill item will produce a random maze in a rectangular area with one
entrance and one exit on opposite sides of the rectangle.  Terrain for the maze
consists of the path terrain and the barrier terrain which are selected with
popup menus in the maze dialog.  Thicknesses of the paths and barriers are then
specified with scroll bars.  The maze generation algorithm requires an odd
number of squares horizontally and vertically.  If an even number is selected,
the maze size will be decreased by one.

Random cities consisting of horizontal and vertical roads can be generated with
the City Fill item inside of rectangular selections.  Note that parks,
consisting mostly of trees, consume a total of four city blocks each.

The Starter Map item will generate a quick rectangular map filled with grass and
framed with water, and with start squares evenly distributed about the
perimeter.  As an option, starter maps with the original Bolo map format
(104x52) can also be generated.

The Random Map item randomly generates an entire Bolo map, including special
squares if the appropriate checkboxes are selected in the Random Map dialog.
This utility is very similar to the RandomMapGenerator written by Peter Lewis
(the algorithm was adapted from the source code for RandomMapGenerator).  Any
existing terrain and all special squares are erased before the map is generated.
The map will be constrained to whatever region is currently selected, if
desired, or a rectangular map centered in the Bolo grid can be selected as an
alternative.  If the 'Deep water inside map' dialog item is not checked, the map
region will be filled with shallow water before the map is generated.
Otherwise, islands generated will be framed with shallow water. Pairs of bases
can be linked with roads using the Connect Bases checkbox. Selecting the In
Pairs checkbox causes an equal number of adjacent bases and pillboxes to be
added in pairs.

Another complete random map utility is the Tiled Random Map, adapted from
Birdman's Map Maker, written by Charles Brabec.  This utility, which was
originally developed to run on Unix computers using standard console (character)
input/output, works by randomly selecting map pieces, called tiles, from a list
of tiles defined in a special kind of Bolo map, called a tile file.  The tiles,
5x5 map squares in size, are selected so that the terrain at the center of the
edges matches previously chosen tiles.  Thus, the tiled map generator has the
unique ability to have terrain propagate through a map.  Other unique features
of the tiled map generator include a nonrandom base and pillbox placement that
uses a distribution algorithm, and the six map symmetry options available, from
no symmetry to 4-fold rotational.  A picture with letters illustrate the current
symmetry selection in the tiled map dialog.  Tiles in tile files that contain
terrain not checked among the allowed terrain checkboxes are rejected for
selection, and the default terrain popup menu selects the terrain that is used
to construct blank tiles.  Blank tiles are created when no tiles can be found in
the list to match existing edges or that fit the checkbox criteria.  Because
there are no checkboxes for mines, boats, or deep water, these terrain types are
always allowed.

Because maps constructed by the tiled map generator are made from the pieces in
a tile file, they are very much a function of the tile file used.  Tile files
consist of rows of 5x5 square map pieces separated by one square of deep water.
Tiles are read from the file one at a time, starting at the upper left corner
and continuing left-to-right, top-to-bottom, until a tile is encountered that is
completely deep sea. Therefore, normal Bolo maps will not be accepted as tile
files because they will be seen as having no tiles.  Bases and pillboxes on the
tiles are used as hints for selecting locations when placing bases and pillboxes
on the new map.  Start squares in tile files, however, are ignored.

The next four items all operate on special squares.  All the bases, pillboxes,
or start squares can be removed with the Remove Specials item.  Set To Defaults
resets the ownership, armor, etc., values of bases and pillboxes to the
defaults.  The Place Bases & PBs item is used to add a number of bases and PBs
to a selected area, or throughout the entire map.  A popup menu of placement
options allows for symmetrical, non-symmetrical, or random placement.  Bases and
pillboxes are never added over 'liquid' terrain, i.e. water, deep water, or
boats, and pillboxes are never located on 'solid' terrain, i.e. buildings or
shot buildings.  The function of the In Pairs checkbox is identical to the
similar checkbox in the Random Map dialog.  Shuffle Bases & PBs randomly changes
the logical order of bases or pillboxes.  This utility will not have any visible
effect on the map, except for changing the numbers that appear when Bolo's base
or pillbox labels options are selected (see the discussion of map windows
above).

The next three items, Clear Mines, Remove Boats, and Replace Terrain, operate on
the entire map, or inside a selected area.  Terrain replacement allows you to
substitute any kind of terrain for another.  If you dislike mines at the
beginning of a game they can be removed with Clear Mines.

Lastly, the Center Terrain utility moves the center of all non-deep water
terrain in the map to the map center, the point 128, 128.  This facility is
provided because the author of Bolo recommends that maps be centered in the
256x256 point map grid.

Windows menu-- The Windows menu can be used to bring other map windows to the
top, and to show the ToolBox if it has been closed.  The first item, Center
Window, scrolls the top map window so that the center point, 128, 128, is in the
center of the window.

11.    Custom Map File Icons
A checkbox option in the preference dialog allows BMAPEdit to create custom file
icons when maps are saved.  These icons are 32x32 pixel images of the map
terrain.  Although the icons give graphical hints about maps, they do have a
couple drawbacks.  First, the icons increase the file size by about 2700 bytes,
an amount that can be several times the size of map files without icons.
Second, in folders with large numbers of custom icons, the time needed to draw
the icons can increase dramatically because the Finder must read each one
separately from the disk.

Another factor to keep in mind is that a new custom icon may not be immediately
visible.  The Macintosh Finder keeps a cache of information it needs to draw
folder windows, and it can be difficult to get the Finder to update a window.
The most successful way seems to be to close and reopen the folder containing
the newly-saved map.  If the new scriptable Finder is available, introduced with
System 7.5, BMAPEdit can tell the Finder to change the icon, in which case the
window will be updated immediately.

If the custom icon option is turned off, BMAPEdit will not create custom icons
for a map file when it is saved, and will remove any existing icons.  This is
because when the map is altered, the icons may not accurately reflect the new
map terrain.

While BMAPEdit can manage custom icons for a single file, it is impractical to
try to use it for a large number of map files.  Another utility called
Iconz4Maps is available for this purpose.  A copy of Iconz4Maps is provided with
the BMAPEdit distribution package.

12.    Special Square Dialogs
These dialogs, which are opened by double-clicking bases, pillboxes, or start
squares with the pointer tool, allow all settings of these special squares to be
selected, including start square direction, initial ownership, base initial
stocks, and pillbox firing intervals.

The pillbox firing interval (or speed) is the number of 20 millisecond periods
between pillbox shots; a 'mad' pillbox fires with a shorter interval between
shots.  Note that the initial firing interval at the beginning of a game decays
rapidly to the idle value of 100.

Ownership is determined by the order in which players join a game, i.e., the
second player to join would automatically own bases that have been set to an
ownership of 2.

Setting a new base or pillbox number causes two bases or pillboxes to swap
positions--all others are not affected.  If the numbering is ignored, they are
numbered in the order they were placed on the map.  Note that, in the case of
pillboxes, this facility is of little use later in the game because PBs can be
killed, moved, and 'replanted'.

The terrain underneath bases and pillboxes can be set in the dialogs.  Also, all
existing bases and pillboxes can be set to identical values with the Set All
Pillboxes or Set All Bases buttons (except for numbering).

13.    Keyboard Shortcuts and Actions
Command key:
*    Produces the pointer cursor while pressed

Space bar:
*    Activates the 'grabber' hand for scrolling in map windows

Escape key (also tab key):
*    Deselects any active selection

Shift key:
*    Dragging new selections with the shift key down produces squares, square
    ovals, and circles.
*    Dragging lines and adding polygon points with the shift key down restricts
    lines and new points to horizontal, vertical, and diagonal directions.
*    Changes pencil tool to the random blob tool.

Option key:
*    Changes magnifier cursor to demagnifier if demagnification is possible.
*    Changes pencil tool to bulldozer for removal of special squares.
*    Clicking and dragging the line tool with the option key pressed produces a
    random walk from the start to the end point.
*    If the option key was pressed when the mouse was clicked while dragging a
    new rectangle, rounded rectangle, or oval selection, the new selection
    expands from the click location, causing the selection to be centered at
    this point.
*    Option-clicking with the polygon tool or the lasso selector causes the
    previous selection point to be replaced.

Control key:
*    Activates the magnifier cursor for changing map views.

ToolBox keyboard shortcuts:
*    D:    Deep water
*    O:    Deep water (Ocean)
*    W:    Water
*    R:    Road
*    G:    Grass
*    F:    Forest
*    T:    Forest (Trees)
*    L:    Building (waLLs)
*    M:    SwaMp
*    C:    Crater
*    B:    Base
*    P:    Pillbox
*    S:    Start square
*    Arrow keys:    moves to next tool in direction of arrow

Start square dialog shortcuts:
*    Tab:    selects next direction counterclockwise (or anti-clockwise)
*    Option-Tab:    selects next direction clockwise
*    Arrow keys:    selects corresponding cardinal direction (N, S, E, or W)

Additional shortcuts:
*    Delete, clear:    clear selection (same as clear item in Edit menu)

Extended keyboard shortcuts:
*    F1, F2, F3, F4:    corresponding Edit menu operations (undo, cut, copy,
    paste)
*    Page Up, Page Down:    same as clicking in vertical scroll bar gray areas
*    Help, Home:    same as clicking in horizontal scroll bar gray areas

14.    Text Import/Export
Each terrain type is translated to/from an ASCII text character.  These are
intended as a method of illustrating written discussions about strategy and
tactics, especially when posted to the Usenet news groups.  Terrain that has
been exported as text will have the proper appearance when displayed in a
mono-spaced font such as Monaco or Courier.  If a proportionally spaced font is
used, map squares in the same vertical column will not line up.

Several drawbacks with using these characters should be noted.  First, start
squares loose their directionality.  Second, the terrain under mines is lost,
i.e. there is no way to indicate whether a mine is on grass, swamp, road,
rubble, crater, or trees.  Third, for a tank in a boat, there is no way to tell
if it is in water or deep water.  Also, damage levels to pillboxes cannot be
determined.  Finally, differentiation of ownership of bases and pillboxes for
players 4 through 16 is not possible.  None of these will prevent the use of the
character set as intended.  The terrain characters are:
deep water          ;
water               :
swamp               s
grass               blank (space)
road                +
forest              #
crater              c
rubble              r
shot building       %
building            O (not zero)
boat                b
neutral base        @
player 1 base       1
player 2 base       2
player 3 base       3
player 4..16 base   4
neutral pillbox     *
player 1 pillbox    7
player 2 pillbox    8
player 3 pillbox    9
player 4..16 PB     0 (not capital 'O')
visible mine        X
invisible mine      x
start square        S
tank                t
tank in boat        T

Please note that when importing text, all other visible characters are changed
to grass.  Also, the terrain for 'T' is interpreted as either water or deep
water depending on the surrounding map squares.  If the number of surrounding
squares that are deep water is three or less, a 'T' is interpreted as water,
otherwise it becomes deep water.  A carriage return (ASCII control-M) begins a
new map row.  When exporting map terrain as text, all mines are invisible
because visibility of mines is not defined in map files, but rather only while a
game is in progress within Bolo itself.

15.    Known Bugs
When dragging selections, quick, rapid, enter and leave movements of the mouse
in and out of the source window can cause the selection outline to be offset
incorrectly.  This is caused by the way dragging is controlled and can't really
be corrected.  Fortunately, it rarely occurs.  Also, under rare conditions,
dragging a selection downward so the window display scroll can leave lines of
old pixels on the screen.  It occurs so infrequently I have not been able to
determine the cause.

16.    Warranty
There are no warranties.  The author makes no guarantees that BMAPEdit will
perform as specified, or that its use will not completely ruin your computer
(but it shouldn't, it hasn't ruined his).

17.    Epilogue
"For example, consider the rise of hypnocracy during April and May of 1972.  The
43 persons constituting the Grateful Dead's (latest) European Tour apportioned
themselves for the most part between two buses which came to be known as the
Bolo bus and the Bozo bus.  The Bolo bus had a john in it and its seats faced
forward.  The Bozo bus had a refrigerator and some of its seats were installed
facing back, to accommodate four tables.  And to look back.  The subtle
difference in character and import and atmosphere between the two omnibuses was
so profoundly hidden and enigmatic that you could never possibly understand it.
The Bozos wore masks, and the Bolos showed their faces.  At one time the Bozos
staged a raid on the Bolo provisions; at one time the Bolo staged a raid on the
Bozo provisions.

"One St. Dilbert defected from the Bozos and lived for a season with the Bolos.
In view of his subsequent martyrdom, his penitence and reconciliation with the
Bozos, it came to be said that he was a true hypnocratic missionary to Bololand.
 And to look back, it appears evident that Bozo and Bolo knew themselves each
the other's raison d'etre.  Is hypnocracy not the aspiration to know what it
is?"
    --Grateful Dead, Europe '72


    "The heavens declare the glory of God;
        the skies proclaim the work of his hands.
    "Day after day they pour forth speech;
        night after night they display knowledge.
    "There is no speech or language
        where their voice is not heard.
    "Their voice goes out into all the earth,
        their words to the ends of the world.
    "He determines the number of the stars,
        and calls them each by name.
    "Great is our Lord and mighty in power;
        his understanding has no limit."
    --Psalm 19:1-4, 147:4, NIV